.TH lha_modapp 1 "14 January 2010" "TrueCL Commands"

.SH NAME
lha_modapp \- Dynamically Change Attributes for a running Application

.SH SYNOPSES
.TS
l l.
clreq	[\fB-A|--application\fP \fIX\fP] [\fB--clear\fP] [\fB--nextnode\fP \fIN\fP] [\fB--nodelist\fP \fIN,...\fP]
	[\fB--syncrate\fP \fIN\fP] [\fB-timeout\fP \fIN\fP] [\fB--force\fP]
	[\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP] [\fB--lwidth\fP \fIN\fP]
.TE

.SH DESCRIPTION
The \fIlha_modapp(1)\fP command is used to change dynamic status attributes of a
currently running application. For example you can change the order of the nodes to
which a fail-over will occur using; or even stop fail-over from occurring at all.

The command can be run on any node that is part of the cluster; the node does not
actually have to be even running in the cluster; and the application in question
can be hosted on any node for the changes to take effect.

The only mandatory argument is the one specifying the application to act on, for example.
.TS
l.
lha_stopapp -A appname
.TE

It should be noted that the changes made affect only the cluster as it currently runs. When the 
cluster is stopped or restarted for whatever reason then the changes entered \fIlha_modapp(1)\fP
will be lost.

.SH ARGUMENTS
.TP 8
--application
This is the name of the currently running application that is to have its attributes changed.
It does not need to be running on the node issuing the command.

Only one application can be specified for any invocation of the command.
.TP
--clear
Clear the current fail-over settings for the application, which will return the
list of nodes that can be used for fail-over back to the default for this application.
.TP
--nextnode 
.B This has not yet been implemented fully and should not be used.
This will change the ordering of the nodes selected for fail-over for the application
to chose the specified node. Once a fail-over has occurred to that node then the 
node order list will return to the default for the application.

If this is set to an empty value than fail-over for this application is disabled
until the \fB--clear\fP option is used.

It is possible to use the special values (put in single quotes) too:

.RS 8
.TP 8
$$NONE
Same as giving an empty value; no next node defined, fail-over is disabled.
.TP
$$LEAST_LOAD
If a fail-over is required then choose from the list of nodes application for
this applicatino that are currently part of the cluster that which has the
lowest running 15 min load average.
.TP
$$LEAST_APPS
Choose the node (from those running and suitable for the application) which 
currently has the lowest number of cluster applications. If two or more nodes
have teh same number (or none) the one chosen from these is pseudo-random.
.TP
$$ROUND_ROBIN
CHose the next available node from thos suitable for the application (based on
sort-ordering of available node names).
.RE

.TP
--nodelist
Specify a comma-separated list of nodes that are considered suitable for the application.
This can be used to indicate a new, temporary, order of fail-over, or to limit the list
of nodes to which the fail-over can occur.
.TP
--syncrate
This defines the synchronisation rate for re-sync of replicated file systems. The value
is givin in KB/sec - and applies for each file system or logical volume defined for
the application.
.TP
--force
If any nodes that should be part of the cluster are not currently contactable via 
the request daemons then any attempt to use \fIlha_modapp(1)\fP will fail by default.
To force through the change without being able to contact all nodes use this argument.
.TP
--timeout
The amount of time to wait for certain responses to requests that are 
necessary for the application to be stopped.  If this is not specified it will
default to 10 [seconds].
.TP
--debug
Run the application modification in 'debug' mode - might produce significant levels 
of output to the standard output device, most of which is only useful for
developers.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of application modification. This is the recommended flag if
the administrator wishes to see any output.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during attempted change of the 
application status.

.SH OUTPUT
None of the output modes generates anything really lengthy. Typically this 
command completes in less than a second and so feedback via the \fB--verbose\fP
option is not typically needed.

.SH EXIT CODES
If the application status is changed as expected, a return code of '0' will be given, 
indicating success. Otherwise a failure is indicated with a return code of '1'.
If a failure does occur then a suitable error message should be shown on the
standard output device too.

.SH FILES
The utility uses the cluster request daemons to handle all changes. Hence any 
changes, problems or errors will be found in the log files for that
daemon, available on each node in the cluster. 

.TS
l l.
clreqd.log	Standard log file for messages.
clreqd.stdout	Will contain any standard output text for the application.
clreqd.stderr	Will contain any error output text for the application.
.TE

.SH NOTES
Remember all settings only exist whilst the cluster is running. If the cluster is
stopped and restarted any changes will be lost and settings will return to default.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2010, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_app_probes(1),
.BR lha_app_routes(1),
.BR lha_buildapp(1),
.BR lha_destroyapp(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

